%
% Copyright (c) 2009-2011,2013 LAAS/CNRS
% All rights reserved.
%
% Permission to use, copy, modify, and distribute this software for any purpose
% with or without   fee is hereby granted, provided   that the above  copyright
% notice and this permission notice appear in all copies.
%
% THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
% REGARD TO THIS  SOFTWARE INCLUDING ALL  IMPLIED WARRANTIES OF MERCHANTABILITY
% AND FITNESS. IN NO EVENT SHALL THE AUTHOR  BE LIABLE FOR ANY SPECIAL, DIRECT,
% INDIRECT, OR CONSEQUENTIAL DAMAGES OR  ANY DAMAGES WHATSOEVER RESULTING  FROM
% LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
% OTHER TORTIOUS ACTION,   ARISING OUT OF OR IN    CONNECTION WITH THE USE   OR
% PERFORMANCE OF THIS SOFTWARE.
%
%                                             Anthony Mallet on Wed Mar  4 2009
%

\section{Configuring robotpkg} % -------------------------------------------
\label{section:configuring}

The whole \robotpkg system is configured  {\em via} a single, centralized file,
called {\tt   robotpkg.conf}  and  placed  in  the   {\tt  /opt/openrobots/etc}
directory  by default.  This location  might be redefined  during the bootstrap
phase,  see  \xref{section:bootstrapping}{Section~\ref{section:bootstrapping}}.
During    the  bootstrap, an initial configuration     file is created with the
settings you provided to {\tt bootstrap}.

The  format of  the configuration file   is that of   the usual GNU style  {\tt
Makefile}s. The whole \robotpkg configuration  is done by setting variables  in
this  file. Note that  you can  define all  kinds of  variables, and no special
error checking (for example for spelling mistakes)  takes place, so you have to
try it out to see if it works.


\subsection{Selecting build options} % -------------------------------------
\label{section:configuring:build_options}

Some packages have   build time options, usually   to select between  different
dependencies,  enable  optional   support for    big   dependencies or   enable
experimental features.

To see   which options, if  any, a   package supports,  and  which  options are
mutually exclusive, run {\tt make show-options}. For example:

\begin{verbatim}
Any of the following general options may be selected:
   api                  Generate module API only
   debug                Produce debugging information for binary programs
*  openprs              Generate OpenPRS client code
*  python               Enable Python client code
*d tcl                  Generate TCL client code
*  tclserv_client       Generate C tclServ client code
   xenomai              Enable Xenomai support
\end{verbatim}

This indicates  that the package  supports a number of options ({\tt api}, {\tt
debug}, {\tt openprs} ...). The currently enabled options are indicated by a
star ({\tt *}) and the default options are shown by the small letter {\tt d} in
front of each option (here, only the {\tt tcl} is enabled by default).

The following variables can be defined  in {\tt robotpkg.conf} to select which
options to enable for a package:

\begin{description}
   \item[{\tt PKG\_DEFAULT\_OPTIONS}] can be used to select or  disable
   options  for  all packages  that  support them,

   \item[{\tt PKG\_OPTIONS.<pkgbase>}] can  be   used  to select  or
   disable   options specifically for package {\tt <pkgbase>}. Options listed
   in these variables are selected, options prefixed by {\tt -} are disabled
   (e.g. {\tt -tcl} would disable the {\tt tcl} option).
\end{description}

A few examples:

\begin{verbatim}
PKG_DEFAULT_OPTIONS=    debug
PKG_OPTIONS.genom=      doc -tcl
\end{verbatim}

It is important to note  that options that were  specifically suggested by  the
package  maintainer must be  explicitely removed if you  do not wish to include
the option.  If you  are unsure you  can view the current  state with {\tt make
show-options}.

The following settings are  consulted in the order  given, and the last setting
that selects or disables an option is used:

\begin{enumerate}
   \item the default options as suggested by the package maintainer,

   \item {\tt PKG\_DEFAULT\_OPTIONS},

   \item {\tt PKG\_OPTIONS.<pkgbase>}
\end{enumerate}

For groups of mutually exclusive options, the last option selected is used, all
others are automatically  disabled.  If  an option of  the  group is explicitly
disabled, the previously selected option,  if any, is used.   It is an error if
no option from  a  required group  of  options is  selected, and  building  the
package will fail.


\subsection{Selecting build alternatives} % --------------------------------
\label{section:configuring:alternatives}

Some  packages  have  alternative   dependencies,  usually  to  select  between
equivalent components or versions of components. This is similar to options but
the  configuration  is  done  globally  for  all packages  that  use  the  same
alternatives (this is to ensure consistency between packages).

To see   which alternatives, if  any, a   package uses, run {\tt make
show-options}. For example:
\begin{verbatim}
Available c-compiler alternatives (PREFER_ALTERNATIVE.c-compiler):
*1 gcc                   Use the GNU C compiler
 2 clang                 Use the LLVM C compiler
   ccache-gcc            Use ccache and the GNU C compiler
   ccache-clang          Use ccache and the LLVM C compiler
\end{verbatim}
This indicates  that the package  supports a {\tt c-compiler}  alternative, for
which {\tt  gcc}, {\tt clang}, {\tt  ccache-gcc} and {\tt  ccache-clang} can be
used. The  currently selected alternative is  shown by the star  ({\tt *}), and
the  user  preferences  (or the  default  if  the  user  has not  set  explicit
preferences) are indicated by the integer in front of the alternative item
(here {\tt gcc} is the preferred alternative, then {\tt clang} should be used
if {\tt gcc} is not available. {\tt ccache} should not be used).

The following variables can be defined  in {\tt robotpkg.conf} to select which
alternative to use:

\begin{description}
   \item[{\tt PREFER\_ALTERNATIVE.<alt>}]
   Alternatives are selected by setting the variable corresponding to the
   alternative ({\tt PREFER\_ALTERNATIVE.c-compiler} in the example above) to a
   space separated list, sorted by order of preference, containing one or
   several of the items shown by {\tt make show-options}.
\end{description}


\subsection{Defining collections of packages} % ----------------------------
\label{section:configuring:sets}

Instead of installing, removing or updating packages one-by-one, you can define
collections  of  packages  in  your  {\tt  robotpkg.conf}.  Once  one  or  more
collections  are defined,  they enable  special targets  that work  on  all the
packages of a collection.

To define a collection, you have to give it a name and list the set of packages
forming  the  collection   in  the  special  {\tt  PKGSET}   variable  in  {\tt
robotpkg.conf}. The syntax is the following:

\begin{verbatim}
PKGSET.<name> = <list>
PKGSET_DESCR.<name> = short, optional description of the collection
\end{verbatim}

where {\tt <name>} is the name of the collection (any string is valid) and {\tt
<list>}  is  the  list  of  packages  in  the  collection,  in  the  form  {\tt
<category>/<name>}. For instance,

\begin{verbatim}
PKGSET.myset = architecture/genom middleware/pocolibs
PKGSET_DESCR.myset = an awesome duo
\end{verbatim}

defines  a collection named  {\tt myset}  that contains  the two  packages {\tt
genom} and {\tt pocolibs} and describes itself with a rather doubtful sentence.

For each collection {\tt <name>}  defined in {\tt robotpkg.conf}, the following
targets   are   available:  {\tt   clean-<name>},   {\tt  fetch-<name>},   {\tt
extract-<name>},    {\tt    install-<name>},    {\tt   replace-<name>},    {\tt
update-<name>}  and {\tt  deinstall-<name>}. They  perform the  same  action as
their  respective counterpart without  {\tt -<name>}  suffix, expect  that they
work on  all packages  of the set.   In addition,  for the {\tt  replace}, {\tt
update} and  {\tt deinstall} targets,  they sort the  packages in the  order of
their dependencies so that the job is done a sensible order.

For  the  user convenience,  two  special  targets  are provided.   The
 ``{\tt installed}'' collection is always defined and represents all currently
installed packages.  Invoking, for  instance, the {\tt update-installed} target
will therefore update all  currently installed packages.  The ``{\tt depends}''
collection is  available only  when the current  working directory is  inside a
package. It merely  defines the current package and all  of its dependencies as
the  sole  elements  of  the  collection.  Invoking,  for  instance,  the  {\tt
update-depends}  target will  update all  dependencies  of the  package in  the
current directory.

Two {\tt robotpkg.conf} variables affect the default behaviour of {\tt
robotpkg} regarding packages sets:

\begin{description}
   \item[PKGSET\_FAILSAFE] When working on a set, and this variable is set to
   yes, robotpkg will continue with further packages instead of stopping on an
   error. If set to 'no', stop on first error. Default: no.

   \item[PKGSET\_STRICT] Specify if package sets should be considered as
   'strict' or include dependencies of packages defined in the set. If set to
   'yes', only package strictly defined in sets are considered. If set to 'no',
   dependencies of packages listed in sets are added to their respective
   sets. Default: no.
\end{description}

Each of these variables can be defined on a per-collection basis, by adding the
.<name> suffix to the variable name, where <name> is the name of the collection
to be configured.


\subsection{Package specific configuration variables} % --------------------

In this  section, you can  find variables that  apply to one  specific package.
Each  variable is  suffixed by  {\tt.<pkg>}, where  {\tt <pkg>}  is  the actual
package name to which the variable should apply.

\begin{description}
   \item[REPOSITORY.<pkg>] locally overrides the default {\tt
   MASTER\_REPOSITORY} defined for a package. This is useful if you want to
   work with an alternative, perhaps local, repository when doing a {\tt make
   checkout}.

   \item[CHECKOUT\_VCS\_OPTS.<pkg>] is a list of options used when fetching a
   package via a {\tt make checkout} command. The options are passed to the
   ``cvs checkout'', ``git clone'' or ``svn checkout'' command that extract the
   source archive.
\end{description}


\subsection{General configuration variables} % -----------------------------

In  this  section,  you can   find some  variables   that apply  to  all \robotpkg
packages.

% A complete  list of the variables that  can be configured by the user
% is  available in <filename>mk/defaults/mk.conf</filename>,  together with  some
% comments that describe each variable's intent.</para>

\begin{description}
   \item[ACCEPTABLE\_LICENSES] List of acceptable licenses. Whenever you try to
   build a package  whose license is  not in this  list, you will get  an error
   message that includes instructions on how to change this variable.

   \item[DISTDIR] Where to store the downloaded copies of the original source
   distributions used for building \robotpkg packages. The default is
   {\tt \${ROBOTPKG\_DIR}/distfiles}.

   \item[PACKAGES] The top level directory for the binary packages. The default
   is  {\tt \${ROBOTPKG\_DIR}/packages}.

%   \item[PKG\_DBDIR] Where the database  about  installed packages  is  stored.
%   The default is {\tt /opt/openrobots/var/db/pkg}.

   \item[MASTER\_SITE\_BACKUP] List  of backup locations for distribution files
   if not found locally  or  in {\tt \${MASTER\_SITES}}.  The default  is\\
   {\tt http://softs.laas.fr/openrobots/robotpkg/distfiles/}.

   \item[PKG\_DEBUG\_LEVEL] The  level of debugging  output  which is displayed
   whilst making and installing the package.  The  default value for this is 0,
   which will not  display the commands as they  are executed (normal, default,
   quiet  operation); the value 1 will  display all shell commands before their
   invocation,  and  the value  2 will  display both the  shell commands before
   their invocation, and their actual execution progress with {\tt set -x}.
\end{description}


\subsection{Variables affecting the build process} % -----------------------

\begin{description}
   \item[WRKOBJDIR] The top level   directory where, if defined,  the  separate
   working directories will get created.  This is useful for building  packages
   on a different filesystem than the \robotpkg sources.

   \item[OBJHOSTNAME] If set to yes (the default), use hostname-specific
   working directories, e.g. work.cactus, work.localhost. {\tt OBJHOSTNAME}
   takes precedence over {\tt OBJMACHINE} (see below).

   \item[OBJMACHINE] If set to yes (the default) use machine-specific working
   directories, e.g. work.Linux-i386.

   \item[DEPENDS\_TARGET] By default,  dependencies are only installed,  and no
   binary package is  created  for them. You  can  set  this variable  to  {\tt
   package}   to   automatically  create    binary  packages   after installing
   dependencies.

   \item[LOCALBASE] Where packages will be installed. The default value is {\tt
   /opt/openrobots}.  Do not  mix     binary  packages with    different values
   of {\tt LOCALBASE}s!

   \item[MAKE\_JOBS] When defined, specifies the maximum number of jobs that
   are run in parallel when building packages with the default action. {\tt
   MAKE\_JOBS} only affects the "build" target. {\tt MAKE\_JOBS} can be set to
   any positive integer; useful values are around the number of processors on
   the machine.

%   \item[GCC\_REQUIRED]  This specifies requirements  on  the version of GCC to
%   use  when  building  packages.   This  variable  should contain   a  list of
%   constraints in the form {\tt  \{<=,<,-,>,>=\}n}. E.g.  to specifiy a minimum
%   version of 4.2  use ``{\tt >=4.2}'', or to  specifiy gcc version 4  only use
%   ``{\tt >=4 <5}''.

\end{description}


\subsection{Additional flags to the compiler} % ----------------------------

If you wish  to set compiler variables   such as {\tt CFLAGS},  {\tt CXXFLAGS},
{\tt FFLAGS} ... please make sure to use  the {\tt +=}  operator instead of the
{\tt {=}} operator:

\begin{verbatim}
CFLAGS+= -your -flags
\end{verbatim}

Using {\tt CFLAGS=} (i.e.  without the ``{\tt +}'') may  lead to  problems with
packages that need to add their own flags.

If you want  to pass flags  to the linker, both in  the configure  step and the
build step, you  can do this  in  two ways.   Either set {\tt  LDFLAGS} or {\tt
LIBS}.  The difference between  the two is that  {\tt LIBS} will be appended to
the command line, while {\tt LDFLAGS} come earlier. {\tt LDFLAGS} is pre-loaded
with rpath settings   for machines that support  it.  As with {\tt CFLAGS}  you
should use the {\tt +=} operator:

\begin{verbatim}
LDFLAGS+= -your -linkerflags
\end{verbatim}
